home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-25 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  49KB  |  906 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: Regexp Search,  Next: Replacement,  Prev: Regular Expressions,  Up: Searching and Matching
  20. Regular Expression Searching
  21. ============================
  22.    In GNU Emacs, you can search for the next match for a regexp either
  23. incrementally or not.  Incremental search commands are described in the
  24. `The GNU Emacs Manual'.  *Note Regular Expression Search: (emacs)Regexp
  25. Search.  Here we describe only the search functions useful in programs.
  26. The principal one is `re-search-forward'.
  27.  - Command: re-search-forward REGEXP &optional LIMIT NOERROR REPEAT
  28.      This function searches forward in the current buffer for a string
  29.      of text that is matched by the regular expression REGEXP.  The
  30.      function skips over any amount of text that is not matched by
  31.      REGEXP, and leaves point at the end of the first string found that
  32.      does match.
  33.      If the search is successful (i.e., if text matching REGEXP is
  34.      found), then point moves to the end of that text, and the function
  35.      returns the new value of point.
  36.      What happens when the search fails depends on the value of
  37.      NOERROR.  If NOERROR is `nil', a `search-failed' error is
  38.      signaled.  If NOERROR is `t', `re-search-forward' does nothing and
  39.      returns `nil'.  If NOERROR is neither `nil' nor `t', then
  40.      `re-search-forward' moves point to LIMIT (or the end of the
  41.      buffer) and returns `nil'.
  42.      If LIMIT is non-`nil' (it must be a position in the current
  43.      buffer), then it is the upper bound to the search.  No match
  44.      extending after that position is accepted.
  45.      If REPEAT is supplied (it must be a positive number), then the
  46.      search is repeated that many times (each time starting at the end
  47.      of the previous time's match).  The call succeeds if all these
  48.      searches succeeded, and point is left at the end of the match
  49.      found by the last search.  Otherwise the search fails.
  50.      In the following example, point is initially located directly
  51.      before the `T'.  After evaluating the form, point is located at
  52.      the end of that line (between the `t' of `hat' and before the
  53.      newline).
  54.           ---------- Buffer: foo ----------
  55.           I read "-!-The cat in the hat
  56.           comes back" twice.
  57.           ---------- Buffer: foo ----------
  58.           
  59.           (re-search-forward "[a-z]+" nil t 5)
  60.                => t
  61.           
  62.           ---------- Buffer: foo ----------
  63.           I read "The cat in the hat-!-
  64.           comes back" twice.
  65.           ---------- Buffer: foo ----------
  66.  - Command: re-search-backward REGEXP &optional LIMIT NOERROR REPEAT
  67.      This function searches backward in the current buffer for a string
  68.      of text that is matched by the regular expression REGEXP, leaving
  69.      point at the beginning of the first text found.
  70.      This function is analogous to `re-search-forward', but they are
  71.      not simple mirror images.  `re-search-forward' finds the match
  72.      whose beginning is as close as possible.  If `re-search-backward'
  73.      were a perfect mirror image, it would find the match whose end is
  74.      as close as possible.  However, in fact it finds the match whose
  75.      beginning is as close as possible.  The reason is that matching a
  76.      regular expression at a given spot always works from beginning to
  77.      end, and is done at a specified beginning position.  Thus, true
  78.      mirror-image behavior would require a special feature for matching
  79.      regexps from end to beginning.
  80.  - Function: string-match REGEXP STRING &optional START
  81.      This function returns the index of the start of the first match for
  82.      the regular expression REGEXP in STRING, or `nil' if there is no
  83.      match.  If START is non-`nil', the search starts at that index in
  84.      STRING.
  85.      For example,
  86.           (string-match
  87.            "quick" "The quick brown fox jumped quickly.")
  88.                => 4
  89.           (string-match
  90.            "quick" "The quick brown fox jumped quickly." 8)
  91.                => 27
  92.      The index of the first character of the string is 0, the index of
  93.      the second character is 1, and so on.
  94.      After this function returns, the index of the first character
  95.      beyond the match is available as `(match-end 0)'.  *Note Match
  96.      Data::.
  97.           (string-match
  98.            "quick" "The quick brown fox jumped quickly." 8)
  99.                => 27
  100.           
  101.           (match-end 0)
  102.                => 32
  103.      The `match-beginning' and `match-end' functions are described
  104.      together; see *Note Match Data::.
  105.  - Function: looking-at REGEXP
  106.      This function determines whether the text in the current buffer
  107.      directly following point matches the regular expression REGEXP.
  108.      "Directly following" means precisely that: the search is
  109.      "anchored" and it must succeed starting with the first character
  110.      following point.  The result is `t' if so, `nil' otherwise.
  111.      This function does not move point, but it updates the match data,
  112.      which you can access using `match-beginning' or `match-end'.
  113.      *Note Match Data::.
  114.      In this example, point is located directly before the `T'.  If it
  115.      were anywhere else, the result would be `nil'.
  116.           ---------- Buffer: foo ----------
  117.           I read "-!-The cat in the hat
  118.           comes back" twice.
  119.           ---------- Buffer: foo ----------
  120.           
  121.           (looking-at "The cat in the hat$")
  122.                => t
  123. File: elisp,  Node: Replacement,  Next: Match Data,  Prev: Regexp Search,  Up: Searching and Matching
  124. Replacement
  125. ===========
  126.  - Function: perform-replace FROM-STRING REPLACEMENTS QUERY-FLAG
  127.           REGEXP-FLAG DELIMITED-FLAG &optional REPEAT-COUNT MAP
  128.      This function is the guts of `query-replace' and related commands.
  129.      It searches for occurrences of FROM-STRING and replaces some or
  130.      all of them.  If QUERY-FLAG is `nil', it replaces all occurrences;
  131.      otherwise, it asks the user what to do about each one.
  132.      If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
  133.      regular expression; otherwise, it must match literally.  If
  134.      DELIMITED-FLAG is non-`nil', then only replacements surrounded by
  135.      word boundaries are considered.
  136.      The argument REPLACEMENTS specifies what to replace occurrences
  137.      with.  If it is a string, that string is used.  It can also be a
  138.      list of strings, to be used in cyclic order.
  139.      If REPEAT-COUNT is non-`nil', it should be an integer, the number
  140.      of occurrences to consider.  In this case, `perform-replace'
  141.      returns after considering that many occurrences.
  142.      Normally, the keymap `query-replace-map' defines the possible user
  143.      responses.  The argument MAP, if non-`nil', is a keymap to use
  144.      instead of `query-replace-map'.
  145.  - Variable: query-replace-map
  146.      This variable holds a special keymap that defines the valid user
  147.      responses for `query-replace' and related functions, as well as
  148.      `y-or-n-p' and `map-y-or-n-p'.  It is special in two ways:
  149.         * The "key bindings" are not commands, just symbols that are
  150.           meaningful to the functions that use this map.
  151.         * Prefix keys are not supported; each key binding must be for a
  152.           single event key sequence.  This is because the functions
  153.           don't use read key sequence to get the input; instead, they
  154.           read a single event and look it up "by hand."
  155.    Here are the meaningful "bindings" for `query-replace-map'.  Several
  156. of them are meaningful only for `query-replace' and friends.
  157. `act'
  158.      Do take the action.  The action being considered--in other words,
  159.      "yes."
  160. `skip'
  161.      Do not take action for this question--in other words, "no."
  162. `exit'
  163.      Answer this question "no," and don't ask any more.
  164. `act-and-exit'
  165.      Answer this question "yes," and don't ask any more.
  166. `act-and-show'
  167.      Answer this question "yes," but show the results--don't advance
  168.      yet.
  169. `automatic'
  170.      Answer this question and all subsequent questions in the series
  171.      with "yes," without further user interaction.
  172. `backup'
  173.      Move back to the previous place that a question was asked about.
  174. `edit'
  175.      Enter a recursive edit to deal with this item--instead of any
  176.      other answer.
  177. `delete-and-edit'
  178.      Delete the text being considered, then enter a recursive edit to
  179.      replace it.
  180. `recenter'
  181.      Redisplay and center the window, then ask the same question again.
  182. `quit'
  183.      Perform a quit right away.  Only the `y-or-n-p' functions use this
  184.      answer.
  185. `help'
  186.      Display some help, then ask again.
  187. File: elisp,  Node: Match Data,  Next: Standard Regexps,  Prev: Replacement,  Up: Searching and Matching
  188. The Match Data
  189. ==============
  190.    Emacs keeps track of the positions of the start and end of segments
  191. of text found during a regular expression search.  This means, for
  192. example, that you can search for a complex pattern, such as a date in
  193. an Rmail message, and extract parts of it.
  194.    Because the match data normally describe the most recent search only,
  195. you must be careful not to do another search inadvertently between the
  196. search you wish to refer back to and the use of the match data.  If you
  197. can't avoid another intervening search, you must save and restore the
  198. match data around it, to prevent it from being overwritten.
  199. * Menu:
  200. * Simple Match Data::     Accessing single items of match data,
  201.                 such as where a particular subexpression started.
  202. * Replacing Match::      Replacing a substring that was matched.
  203. * Entire Match Data::     Accessing the entire match data at once, as a list.
  204. * Saving Match Data::     Saving and restoring the match data.
  205. File: elisp,  Node: Simple Match Data,  Next: Replacing Match,  Up: Match Data
  206. Simple Match Data Access
  207. ------------------------
  208.    This section explains how to use the match data to find the starting
  209. point or ending point of the text that was matched by a particular
  210. search, or by a particular parenthetical subexpression of a regular
  211. expression.
  212.  - Function: match-beginning COUNT
  213.      This function returns the position of the start of text matched by
  214.      the last regular expression searched for.  COUNT, a number,
  215.      specifies a subexpression whose start position is the value.  If
  216.      COUNT is zero, then the value is the position of the text matched
  217.      by the whole regexp.  If COUNT is greater than zero, then the
  218.      value is the position of the beginning of the text matched by the
  219.      COUNTth subexpression, regardless of whether it was used in the
  220.      final match.
  221.      Subexpressions of a regular expression are those expressions
  222.      grouped inside of parentheses, `\(...\)'.  The COUNTth
  223.      subexpression is found by counting occurrences of `\(' from the
  224.      beginning of the whole regular expression.  The first
  225.      subexpression is numbered 1, the second 2, and so on.
  226.      The value is `nil' for a parenthetical grouping inside of a `\|'
  227.      alternative that wasn't used in the match.
  228.      The `match-end' function is similar to the `match-beginning'
  229.      function except that it returns the position of the end of the
  230.      matched text.
  231.      Here is an example, with a comment showing the numbers of the
  232.      positions in the text:
  233.           (string-match
  234.            "\\(qu\\)\\(ick\\)" "The quick fox jumped quickly.")
  235.                => 4            ;^^^^^^^^^^
  236.                                ;0123456789
  237.           (match-beginning 1)               ; The beginning of the match
  238.                => 4                         ;   with `qu' is at index 4.
  239.           (match-beginning 2)               ; The beginning of the match
  240.                => 6                         ;   with `ick' is at index 6.
  241.           (match-end 1)                     ; The end of the match
  242.                => 6                         ;   with `qu' is at index 6.
  243.           
  244.           (match-end 2)                     ; The end of the match
  245.                => 9                         ;   with `ick' is at index 9.
  246.      Here is another example.  Before the form is evaluated, point is
  247.      located at the beginning of the line.  After evaluating the search
  248.      form, point is located on the line between the space and the word
  249.      `in'.  The beginning of the entire match is at the 9th character
  250.      of the buffer (`T'), and the beginning of the match for the first
  251.      subexpression is at the 13th character (`c').
  252.           (list
  253.             (re-search-forward "The \\(cat \\)")
  254.             (match-beginning 0)
  255.             (match-beginning 1))
  256.               => (t 9 13)
  257.           
  258.           ---------- Buffer: foo ----------
  259.           I read "The cat -!-in the hat comes back" twice.
  260.                   ^   ^
  261.                   9  13
  262.           ---------- Buffer: foo ----------
  263.      (Note that in this case, the index returned is a buffer position;
  264.      the first character of the buffer counts as 1.)
  265.  - Function: match-end COUNT
  266.      This function returns the position of the end of text matched by
  267.      the last regular expression searched for.  This function is
  268.      otherwise similar to `match-beginning'.
  269. File: elisp,  Node: Replacing Match,  Next: Entire Match Data,  Prev: Simple Match Data,  Up: Match Data
  270. Replacing the Text That Matched
  271. -------------------------------
  272.  - Function: replace-match REPLACEMENT &optional FIXEDCASE LITERAL
  273.      This function replaces the text matched by the last search with
  274.      REPLACEMENT.
  275.      If FIXEDCASE is non-`nil', then the case of the replacement text
  276.      is not changed; otherwise, the replacement text is converted to a
  277.      different case depending upon the capitalization of the text to be
  278.      replaced.  If the original text is all upper case, the replacement
  279.      text is converted to upper case, except when all of the words in
  280.      the original text are only one character long.  In that event, the
  281.      replacement text is capitalized.  If *all* of the words in the
  282.      original text are capitalized, then all of the words in the
  283.      replacement text are capitalized.
  284.      If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
  285.      it is, the only alterations being case changes as needed.  If it
  286.      is `nil' (the default), then the character `\' is treated
  287.      specially.  If a `\' appears in REPLACEMENT, then it must be part
  288.      of one of the following sequences:
  289.     `\&'
  290.           `\&' stands for the entire text being replaced.
  291.     `\N'
  292.           `\N' stands for the Nth subexpression in the original regexp.
  293.           Subexpressions are those expressions grouped inside of
  294.           `\(...\)'.  N is a digit.
  295.     `\\'
  296.           `\\' stands for a single `\' in the replacement text.
  297.      `replace-match' leaves point at the end of the replacement text,
  298.      and returns `t'.
  299. File: elisp,  Node: Entire Match Data,  Next: Saving Match Data,  Prev: Replacing Match,  Up: Match Data
  300. Accessing the Entire Match Data
  301. -------------------------------
  302.    The functions `match-data' and `store-match-data' let you read or
  303. write the entire match data, all at once.
  304.  - Function: match-data
  305.      This function returns a new list containing all the information on
  306.      what text the last search matched.  Element zero is the position
  307.      of the beginning of the match for the whole expression; element
  308.      one is the position of the end of the match for the expression.
  309.      The next two elements are the positions of the beginning and end
  310.      of the match for the first subexpression.  In general, element
  311.      number 2N corresponds to `(match-beginning N)'; and element number
  312.      2N + 1 corresponds to `(match-end N)'.
  313.      All the elements are markers or `nil' if matching was done on a
  314.      buffer, and all are integers or `nil' if matching was done on a
  315.      string with `string-match'.  (In Emacs 18 and earlier versions,
  316.      markers were used even for matching on a string, except in the case
  317.      of the integer 0.)
  318.      As always, there must be no possibility of intervening searches
  319.      between the call to a search function and the call to `match-data'
  320.      that is intended to access the match-data for that search.
  321.           (match-data)
  322.                =>  (#<marker at 9 in foo>
  323.                     #<marker at 17 in foo>
  324.                     #<marker at 13 in foo>
  325.                     #<marker at 17 in foo>)
  326.  - Function: store-match-data MATCH-LIST
  327.      This function sets the match data from the elements of MATCH-LIST,
  328.      which should be a list that was the value of a previous call to
  329.      `match-data'.
  330.      If MATCH-LIST refers to a buffer that doesn't exist, you don't get
  331.      an error; that sets the match data in a meaningless but harmless
  332.      way.
  333. File: elisp,  Node: Saving Match Data,  Prev: Entire Match Data,  Up: Match Data
  334. Saving and Restoring the Match Data
  335. -----------------------------------
  336.    All asynchronous process functions (filters and sentinels) and
  337. functions that use `recursive-edit' should save and restore the match
  338. data if they do a search or if they let the user type arbitrary
  339. commands.  Saving the match data is useful in other cases as
  340. well--whenever you want to access the match data resulting from an
  341. earlier search, notwithstanding another intervening search.
  342.    This example shows the problem that can arise if you fail to attend
  343. to this requirement:
  344.      (re-search-forward "The \\(cat \\)")
  345.           => 48
  346.      (foo)                   ; Perhaps `foo' does
  347.                              ;   more searching.
  348.      (match-end 0)
  349.           => 61              ; Unexpected result---not 48!
  350.    In Emacs versions 19 and later, you can save and restore the match
  351. data with `save-match-data':
  352.  - Special Form: save-match-data BODY...
  353.      This special form executes BODY, saving and restoring the match
  354.      data around it.  This is useful if you wish to do a search without
  355.      altering the match data that resulted from an earlier search.
  356.    You can use `store-match-data' together with `match-data' to imitate
  357. the effect of the special form `save-match-data'.  This is useful for
  358. writing code that can run in Emacs 18.  Here is how:
  359.      (let ((data (match-data)))
  360.        (unwind-protect
  361.            ...   ; May change the original match data.
  362.          (store-match-data data)))
  363. File: elisp,  Node: Standard Regexps,  Next: Searching and Case,  Prev: Match Data,  Up: Searching and Matching
  364. Standard Regular Expressions Used in Editing
  365. ============================================
  366.    Here are the regular expressions standardly used in editing:
  367.  - Variable: page-delimiter
  368.      This is the regexp describing line-beginnings that separate pages.
  369.      The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"').
  370.  - Variable: paragraph-separate
  371.      This is the regular expression for recognizing the beginning of a
  372.      line that separates paragraphs.  (If you change this, you may have
  373.      to change `paragraph-start' also.)  The default value is `"^[
  374.      \t\f]*$"', which is a line that consists entirely of spaces, tabs,
  375.      and form feeds.
  376.  - Variable: paragraph-start
  377.      This is the regular expression for recognizing the beginning of a
  378.      line that starts *or* separates paragraphs.  The default value is
  379.      `"^[ \t\n\f]"', which matches a line starting with a space, tab,
  380.      newline, or form feed.
  381.  - Variable: sentence-end
  382.      This is the regular expression describing the end of a sentence.
  383.      (All paragraph boundaries also end sentences, regardless.)  The
  384.      default value is:
  385.           "[.?!][]\"')}]*\\($\\|\t\\| \\)[ \t\n]*"
  386.      This means a period, question mark or exclamation mark, followed
  387.      by a closing brace, followed by tabs, spaces or new lines.
  388.      For a detailed explanation of this regular expression, see *Note
  389.      Regexp Example::.
  390. File: elisp,  Node: Searching and Case,  Prev: Standard Regexps,  Up: Searching and Matching
  391. Searching and Case
  392. ==================
  393.    By default, searches in Emacs ignore the case of the text they are
  394. searching through; if you specify searching for `FOO', then `Foo' or
  395. `foo' is also considered a match.  Regexps, and in particular character
  396. sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.
  397.    If you do not want this feature, set the variable `case-fold-search'
  398. to `nil'.  Then all letters must match exactly, including case.  This
  399. is a per-buffer-local variable; altering the variable affects only the
  400. current buffer.  (*Note Intro to Buffer-Local::.)  Alternatively, you
  401. may change the value of `default-case-fold-search', which is the
  402. default value of `case-fold-search' for buffers that do not override it.
  403.  - User Option: case-replace
  404.      This variable determines whether `query-replace' should preserve
  405.      case in replacements.  If the variable is `nil', then case need
  406.      not be preserved.
  407.  - User Option: case-fold-search
  408.      This buffer-local variable determines whether searches should
  409.      ignore case.  If the variable is `nil' they do not ignore case;
  410.      otherwise they do ignore case.
  411.  - Variable: default-case-fold-search
  412.      The value of this variable is the default value for
  413.      `case-fold-search' in buffers that do not override it.  This is the
  414.      same as `(default-value 'case-fold-search)'.
  415. File: elisp,  Node: Syntax Tables,  Next: Abbrevs,  Prev: Searching and Matching,  Up: Top
  416. Syntax Tables
  417. *************
  418.    A "syntax table" provides Emacs with the information that determines
  419. the syntactic use of each character in a buffer.  This information is
  420. used by the parsing commands, the complex movement commands, and others
  421. to determine where words, symbols, and other syntactic constructs begin
  422. and end.  The current syntax table controls the meaning of the word
  423. motion functions (*note Word Motion::.) and the list motion functions
  424. (*note List Motion::.) as well as the functions in this chapter.
  425.    A syntax table is a vector of 256 elements; it contains one entry for
  426. each of the 256 ASCII characters of an 8-bit byte.  Each element is an
  427. integer that encodes the syntax of the character in question.
  428.    Syntax tables are used only for moving across text, not for the GNU
  429. Emacs Lisp reader.  GNU Emacs Lisp uses built-in syntactic rules when
  430. reading Lisp expressions, and these rules cannot be changed.
  431.    Each buffer has its own major mode, and each major mode has its own
  432. idea of the syntactic class of various characters.  For example, in Lisp
  433. mode, the character `;' begins a comment, but in C mode, it terminates
  434. a statement.  To support these variations, Emacs makes the choice of
  435. syntax table local to each buffer.  Typically, each major mode has its
  436. own syntax table and installs that table in each buffer which uses that
  437. mode.  Changing this table alters the syntax in all those buffers as
  438. well as in any buffers subsequently put in that mode.  Occasionally
  439. several similar modes share one syntax table.  *Note Example Major
  440. Modes::, for an example of how to set up a syntax table.
  441.  - Function: syntax-table-p OBJECT
  442.      This function returns `t' if OBJECT is a vector of length 256
  443.      elements.  This means that the vector may be a syntax table.
  444.      However, according to this test, any vector of length 256 is
  445.      considered to be a syntax table, no matter what its contents.
  446. * Menu:
  447. * Syntax Descriptors::       How characters are classified.
  448. * Syntax Table Functions::   How to create, examine and alter syntax tables.
  449. * Motion and Syntax::         Moving over characters with certain syntaxes.
  450. * Parsing Expressions::      Parsing balanced expressions
  451.                                 using the syntax table.
  452. * Standard Syntax Tables::   Syntax tables used by various major modes.
  453. * Syntax Table Internals::   How syntax table information is stored.
  454. File: elisp,  Node: Syntax Descriptors,  Next: Syntax Table Functions,  Up: Syntax Tables
  455. Syntax Descriptors
  456. ==================
  457.    This section describes the syntax classes and flags that denote the
  458. syntax of a character, and how they are represented as a "syntax
  459. descriptor", which is a Lisp string that you pass to
  460. `modify-syntax-entry' to specify the desired syntax.
  461.    Emacs defines twelve "syntax classes".  Each syntax table puts each
  462. character into one class.  There is no necessary relationship between
  463. the class of a character in one syntax table and its class in any other
  464. table.
  465.    Each class is designated by a mnemonic character which serves as the
  466. name of the class when you need to specify a class.  Usually the
  467. designator character is one which is frequently put in that class;
  468. however, its meaning as a designator is unvarying and independent of how
  469. it is actually classified.
  470.    A syntax descriptor is a Lisp string which specifies a syntax class,
  471. a matching character (unused except for parenthesis classes) and flags.
  472. The first character is the designator for a syntax class.  The second
  473. character is the character to match; if it is unused, put a space there.
  474. Then come the characters for any desired flags.  If no matching
  475. character or flags are needed, one character is sufficient.
  476.    Thus, the descriptor for the character `*' in C mode is `. 23'
  477. (i.e., punctuation, matching character slot unused, second character of
  478. a comment-starter, first character of an comment-ender), and the entry
  479. for `/' is `. 14' (i.e., punctuation, matching character slot unused,
  480. first character of a comment-starter, second character of a
  481. comment-ender).
  482. * Menu:
  483. * Syntax Class Table::      Table of syntax classes.
  484. * Syntax Flags::            Additional flags each character can have.
  485. File: elisp,  Node: Syntax Class Table,  Next: Syntax Flags,  Up: Syntax Descriptors
  486. Table of Syntax Classes
  487. -----------------------
  488.    Here is a summary of the classes, the characters that stand for them,
  489. their meanings, and examples of their use.
  490.  - Syntax class: whitespace character
  491.      "Whitespace characters" (designated with ` ' or `-') separate
  492.      symbols and words from each other.  Typically, whitespace
  493.      characters have no other syntactic use, and multiple whitespace
  494.      characters are syntactically equivalent to a single one.  Space,
  495.      tab, newline and formfeed are almost always considered whitespace.
  496.  - Syntax class: word constituent
  497.      "Word constituents" (designated with `w') are parts of normal
  498.      English words and are typically used in variable and command names
  499.      in programs.  All upper and lower case letters and the digits are
  500.      typically word constituents.
  501.  - Syntax class: symbol constituent
  502.      "Symbol constituents" (designated with `_') are the extra
  503.      characters that are used in variable and command names along with
  504.      word constituents.  For example, the symbol constituents class is
  505.      used in Lisp mode to indicate that certain characters may be part
  506.      of symbol names even though they are not part of English words.
  507.      These characters are `$&*+-_<>'.  In standard C, the only
  508.      non-word-constituent character that is valid in symbols is
  509.      underscore (`_').
  510.  - Syntax class: punctuation character
  511.      "Punctuation characters" (`.') are those characters that are used
  512.      as punctuation in English, or are used in some way in a programming
  513.      language to separate symbols from one another.  Most programming
  514.      language modes, including Emacs Lisp mode, have no characters in
  515.      this class since the few characters that are not symbol or word
  516.      constituents all have other uses.
  517.  - Syntax class: open parenthesis character
  518.  - Syntax class: close parenthesis character
  519.      Open and close "parenthesis characters" are characters used in
  520.      dissimilar pairs to surround sentences or expressions.  Such a
  521.      grouping is begun with an open parenthesis character and
  522.      terminated with a close.  Each open parenthesis character matches
  523.      a particular close parenthesis character, and vice versa.
  524.      Normally, Emacs indicates momentarily the matching open
  525.      parenthesis when you insert a close parenthesis.  *Note Blinking::.
  526.      The class of open parentheses is designated with `(', and that of
  527.      close parentheses with `)'.
  528.      In English text, and in C code, the parenthesis pairs are `()',
  529.      `[]', and `{}'.  In Emacs Lisp, the delimiters for lists and
  530.      vectors (`()' and `[]') are classified as parenthesis characters.
  531.  - Syntax class: string quote
  532.      "String quote characters" (designated with `"') is used to delimit
  533.      string constants in many languages, including Lisp and C.  The
  534.      same string quote character appears at the beginning and the end
  535.      of a string.  Such quoted strings do not nest.
  536.      The parsing facilities of Emacs consider a string as a single
  537.      token.  The usual syntactic meanings of the characters in the
  538.      string are suppressed.
  539.      The Lisp modes have two string quote characters: double-quote (`"')
  540.      and vertical bar (`|').  `|' is not used in Emacs Lisp, but it is
  541.      used in Common Lisp.  C also has two string quote characters:
  542.      double-quote for strings, and single-quote (`'') for character
  543.      constants.
  544.      English text has no string quote characters because English is not
  545.      a programming language.  Although quotation marks are used in
  546.      English, we do not want them to turn off the usual syntactic
  547.      properties of other characters in the quotation.
  548.  - Syntax class: escape
  549.      An "escape character" (designated with `\') starts an escape
  550.      sequence such as is used in C string and character constants.  The
  551.      character `\' belongs to this class in both C and Lisp.  (In C, it
  552.      is used thus only inside strings, but it turns out to cause no
  553.      trouble to treat it this way throughout C code.)
  554.      Characters in this class count as part of words if
  555.      `words-include-escapes' is non-`nil'.  *Note Word Motion::.
  556.  - Syntax class: character quote
  557.      A "character quote character" (designated with `/') quotes the
  558.      following character so that it loses its normal syntactic meaning.
  559.      This differs from an escape character in that only the character
  560.      immediately following is ever affected.
  561.      Characters in this class count as part of words if
  562.      `words-include-escapes' is non-`nil'.  *Note Word Motion::.
  563.      This class is not currently used in any standard Emacs modes.
  564.  - Syntax class: paired delimiter
  565.      "Paired delimiter characters" (designated with `$') are like
  566.      string quote characters except that the syntactic properties of the
  567.      characters between the delimiters are not suppressed.  Only TeX
  568.      mode uses a paired identical delimiter presently--the `$' that
  569.      begins and ends math mode.
  570.  - Syntax class: expression prefix
  571.      An "expression prefix operator" (designated with `'') is used for
  572.      syntactic operators that are part of an expression if they appear
  573.      next to one but are not part of an adjoining symbol.  These
  574.      characters in Lisp include the apostrophe, `'' (used for quoting),
  575.      the comma, `,' (used in macros), and `#' (used in the read syntax
  576.      for certain data types).
  577.  - Syntax class: comment starter
  578.  - Syntax class: comment ender
  579.      The "comment starter" and "comment ender" characters are used in
  580.      different languages to delimit comments.  These classes are
  581.      designated with `<' and `>', respectively.
  582.      English text has no comment characters.  In Lisp, the semicolon
  583.      (`;') starts a comment and a newline or formfeed ends one.
  584. File: elisp,  Node: Syntax Flags,  Prev: Syntax Class Table,  Up: Syntax Descriptors
  585. Syntax Flags
  586. ------------
  587.    In addition to the classes, entries for characters in a syntax table
  588. can include flags.  There are six possible flags, represented by the
  589. characters `1', `2', `3', `4', `b' and `p'.
  590.    All the flags except `p' are used to describe multi-character
  591. comment delimiters.  The digit flags indicate that a character can
  592. *also* be part of a comment sequence, in addition to the syntactic
  593. properties associated with its character class.  The flags are
  594. independent of the class and each other for the sake of characters such
  595. as `*' in C mode, which is a punctuation character, *and* the second
  596. character of a start-of-comment sequence (`/*'), *and* the first
  597. character of an end-of-comment sequence (`*/').
  598.    The flags for a character C are:
  599.    * `1' means C is the start of a two-character comment start sequence.
  600.    * `2' means C is the second character of such a sequence.
  601.    * `3' means C is the start of a two-character comment end sequence.
  602.    * `4' means C is the second character of such a sequence.
  603.    * `b' means that C as a comment delimiter belongs to the alternative
  604.      "b" comment style.
  605.      Emacs can now supports two comment styles simultaneously.  (This
  606.      is for the sake of C++.)  More specifically, it can recognize two
  607.      different comment-start sequences.  Both must share the same first
  608.      character; only the second character may differ.  Mark the second
  609.      character of the "b"-style comment start sequence with the `b'
  610.      flag.
  611.      The two styles of comment can have different comment-end
  612.      sequences.  A comment-end sequence (one or two characters) applies
  613.      to the "b" style if its first character has the `b' flag set;
  614.      otherwise, it applies to the "a" style.
  615.      The appropriate comment syntax settings for C++ are as follows:
  616.     `/'
  617.           `124b'
  618.     `*'
  619.           `23'
  620.     newline
  621.           `>b'
  622.      Thus `/*' is a comment-start sequence for "a" style, `//' is a
  623.      comment-start sequence for "b" style, `*/' is a comment-end
  624.      sequence for "a" style, and newline is a comment-end sequence for
  625.      "b" style.
  626.    * `p' identifies an additional "prefix character" for Lisp syntax.
  627.      These characters are treated as whitespace when they appear between
  628.      expressions.  When they appear within an expression, they are
  629.      handled according to their usual syntax codes.
  630.      The function `backward-prefix-chars' moves back over these
  631.      characters, as well as over characters whose primary syntax class
  632.      is prefix (`'').
  633. File: elisp,  Node: Syntax Table Functions,  Next: Motion and Syntax,  Prev: Syntax Descriptors,  Up: Syntax Tables
  634. Syntax Table Functions
  635. ======================
  636.    In this section we describe functions for creating, accessing and
  637. altering syntax tables.
  638.  - Function: make-syntax-table &optional TABLE
  639.      This function constructs a copy of TABLE and returns it.  If TABLE
  640.      is not supplied (or is `nil'), it returns a copy of the current
  641.      syntax table.  Otherwise, an error is signaled if TABLE is not a
  642.      syntax table.
  643.  - Function: copy-syntax-table &optional TABLE
  644.      This function is identical to `make-syntax-table'.
  645.  - Command: modify-syntax-entry CHAR SYNTAX-DESCRIPTOR &optional TABLE
  646.      This function sets the syntax entry for CHAR according to
  647.      SYNTAX-DESCRIPTOR.  The syntax is changed only for TABLE, which
  648.      defaults to the current buffer's syntax table, and not in any
  649.      other syntax table.  The argument SYNTAX-DESCRIPTOR specifies the
  650.      desired syntax; this is a string beginning with a class designator
  651.      character, and optionally containing a matching character and
  652.      flags as well.  *Note Syntax Descriptors::.
  653.      This function always returns `nil'.  The old syntax information in
  654.      the table for this character is discarded.
  655.      An error is signaled if the first character of the syntax
  656.      descriptor is not one of the twelve syntax class designator
  657.      characters.  An error is also signaled if CHAR is not a character.
  658.      Examples:
  659.           ;; Put the space character in class whitespace.
  660.           (modify-syntax-entry ?\  " ")
  661.                => nil
  662.           
  663.           ;; Make `$' an open parenthesis character,
  664.           ;;   with `^' as its matching close.
  665.           (modify-syntax-entry ?$ "(^")
  666.                => nil
  667.           
  668.           ;; Make `^' a close parenthesis character,
  669.           ;;   with `$' as its matching open.
  670.           (modify-syntax-entry ?^ ")$")
  671.                => nil
  672.           
  673.           ;; Make `/' a punctuation character,
  674.           ;;   the first character of a start-comment sequence,
  675.           ;;   and the second character of an end-comment sequence.
  676.           ;;   This is used in C mode.
  677.           (modify-syntax-entry ?/ ".13")
  678.                => nil
  679.  - Function: char-syntax CHARACTER
  680.      This function returns the syntax class of CHARACTER, represented
  681.      by its mnemonic designator character.  This *only* returns the
  682.      class, not any matching parenthesis or flags.
  683.      An error is signaled if CHAR is not a character.
  684.      The first example shows that the syntax class of space is
  685.      whitespace (represented by a space).  The second example shows
  686.      that the syntax of `/' is punctuation in C-mode.  This does not
  687.      show the fact that it is also a comment sequence character.  The
  688.      third example shows that open parenthesis is in the class of open
  689.      parentheses.  This does not show the fact that it has a matching
  690.      character, `)'.
  691.           (char-to-string (char-syntax ?\ ))
  692.                => " "
  693.           
  694.           (char-to-string (char-syntax ?/))
  695.                => "."
  696.           
  697.           (char-to-string (char-syntax ?\())
  698.                => "("
  699.  - Function: set-syntax-table TABLE
  700.      This function makes TABLE the syntax table for the current buffer.
  701.      It returns TABLE.
  702.  - Function: syntax-table
  703.      This function returns the current syntax table, which is the table
  704.      for the current buffer.
  705. File: elisp,  Node: Motion and Syntax,  Next: Parsing Expressions,  Prev: Syntax Table Functions,  Up: Syntax Tables
  706. Motion and Syntax
  707. =================
  708.    This section describes functions for moving across characters in
  709. certain syntax classes.  None of these functions exists in Emacs
  710. version 18 or earlier.
  711.  - Function: skip-syntax-forward SYNTAXES &optional LIMIT
  712.      This function moves point forward across characters whose syntax
  713.      classes are mentioned in SYNTAXES.  It stops when it encounters
  714.      the end of the buffer, or position LIM (if specified), or a
  715.      character it is not supposed to skip.
  716.      The return value is the distance traveled, which is a nonnegative
  717.      integer.
  718.  - Function: skip-syntax-backward SYNTAXES &optional LIMIT
  719.      This function moves point backward across characters whose syntax
  720.      classes are mentioned in SYNTAXES.  It stops when it encounters
  721.      the beginning of the buffer, or position LIM (if specified), or a
  722.      character it is not supposed to skip.
  723.      The return value indicates the distance traveled.  It is an
  724.      integer that is zero or less.
  725.  - Function: backward-prefix-chars
  726.      This function moves point backward over any number of chars with
  727.      expression prefix syntax.  This includes both characters in the
  728.      expression prefix syntax class, and characters with the `p' flag.
  729. File: elisp,  Node: Parsing Expressions,  Next: Standard Syntax Tables,  Prev: Motion and Syntax,  Up: Syntax Tables
  730. Parsing Balanced Expressions
  731. ============================
  732.    Here are several functions for parsing and scanning balanced
  733. expressions.  The syntax table controls the interpretation of
  734. characters, so these functions can be used for Lisp expressions when in
  735. Lisp mode and for C expressions when in C mode.  *Note List Motion::,
  736. for convenient higher-level functions for moving over balanced
  737. expressions.
  738.  - Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH
  739.           STOP-BEFORE STATE STOP-COMMENT
  740.      This function parses an expression in the current buffer starting
  741.      at START, not scanning past LIMIT.  Parsing stops at LIMIT or when
  742.      certain criteria described below are met; point is set to the
  743.      location where parsing stops.  The value returned is a description
  744.      of the status of the parse at the point where it stops.
  745.      Normally, START is assumed to be the top level of an expression to
  746.      be parsed, such as the beginning of a function definition.
  747.      Alternatively, you might wish to resume parsing in the middle of an
  748.      expression.  To do this, you must provide a STATE argument that
  749.      describes the initial status of parsing.  If STATE is omitted (or
  750.      `nil'), parsing assumes that START is the beginning of a new parse
  751.      at level 0.
  752.      If the third argument TARGET-DEPTH is non-`nil', parsing stops if
  753.      the depth in parentheses becomes equal to TARGET-DEPTH.  The depth
  754.      starts at 0, or at whatever is given in STATE.
  755.      If the fourth argument STOP-BEFORE is non-`nil', parsing stops
  756.      when it comes to any character that starts a sexp.  If
  757.      STOP-COMMENT is non-`nil', parsing stops when it comes to the
  758.      start of a comment.
  759.      The fifth argument STATE is a seven-element list of the same form
  760.      as the value of this function, described below.  The return value
  761.      of one call may be used to initialize the state of the parse on
  762.      another call to `parse-partial-sexp'.
  763.      The result is a list of seven elements describing the final state
  764.      of the parse:
  765.        0. The depth in parentheses, starting at 0.
  766.        1. The character position of the start of the innermost
  767.           containing parenthetical grouping; `nil' if none.
  768.        2. The character position of the start of the last complete
  769.           subexpression terminated; `nil' if none.
  770.        3. Non-`nil' if inside a string.  (It is the character that will
  771.           terminate the string.)
  772.        4. `t' if inside a comment.
  773.        5. `t' if point is just after a quote character.
  774.        6. The minimum parenthesis depth encountered during this scan.
  775.      Elements 1, 4, 5, and 6 are significant in the argument STATE.
  776.      This function is used to determine how to indent lines in programs
  777.      written in languages that have nested parentheses.
  778.  - Function: scan-lists FROM COUNT DEPTH
  779.      This function scans forward COUNT balanced parenthetical groupings
  780.      from character number FROM.  It returns the character number of
  781.      the position thus found.
  782.      If DEPTH is nonzero, parenthesis depth counting begins from that
  783.      value.  The only candidates for stopping are places where the
  784.      depth in parentheses becomes zero; `scan-lists' counts COUNT such
  785.      places and then stops.  Thus, a positive value for DEPTH means go
  786.      out levels of parenthesis.
  787.      Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'.
  788.      If the beginning or end of the buffer (or its accessible portion)
  789.      is reached and the depth is not zero, an error is signaled.  If
  790.      the depth is zero but the count is not used up, `nil' is returned.
  791.  - Function: scan-sexps FROM COUNT
  792.      Scan from character number FROM by COUNT balanced expressions.  It
  793.      returns the character number of the position thus found.
  794.      Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'.
  795.      If the beginning or end of (the accessible part of) the buffer is
  796.      reached in the middle of a parenthetical grouping, an error is
  797.      signaled.  If the beginning or end is reached between groupings but
  798.      before count is used up, `nil' is returned.
  799.  - Variable: parse-sexp-ignore-comments
  800.      If the value is non-`nil', then comments are treated as whitespace
  801.      by the functions in this section and by `forward-sexp'.
  802.      In older Emacs versions, this feature worked only when the comment
  803.      terminator is something like `*/', and appears only to end a
  804.      comment.  In languages where newlines terminate comments, it was
  805.      necessary make this variable `nil', since not every newline is the
  806.      end of a comment.  This limitation no longer exists.
  807.    You can use `forward-comment' to move forward or backward over one
  808. comment or several comments.
  809.  - Function: forward-comment COUNT
  810.      This function moves point forward across COUNT comments (backward,
  811.      if COUNT is negative).  If it finds anything other than a comment
  812.      or whitespace, it stops, leaving point at the place where it
  813.      stopped.  It also stops after satisfying COUNT.
  814.    To move forward over all comments and whitespace following point, use
  815. `(forward-comment (buffer-size))'.  `(buffer-size)' is a good argument
  816. to use, because the number of comments to skip cannot exceed that many.
  817. File: elisp,  Node: Standard Syntax Tables,  Next: Syntax Table Internals,  Prev: Parsing Expressions,  Up: Syntax Tables
  818. Some Standard Syntax Tables
  819. ===========================
  820.    Each of the major modes in Emacs has its own syntax table.  Here are
  821. several of them:
  822.  - Function: standard-syntax-table
  823.      This function returns the standard syntax table, which is the
  824.      syntax table used in Fundamental mode.
  825.  - Variable: text-mode-syntax-table
  826.      The value of this variable is the syntax table used in Text mode.
  827.  - Variable: c-mode-syntax-table
  828.      The value of this variable is the syntax table in use in C-mode
  829.      buffers.
  830.  - Variable: emacs-lisp-mode-syntax-table
  831.      The value of this variable is the syntax table used in Emacs Lisp
  832.      mode by editing commands.  (It has no effect on the Lisp `read'
  833.      function.)
  834. File: elisp,  Node: Syntax Table Internals,  Prev: Standard Syntax Tables,  Up: Syntax Tables
  835. Syntax Table Internals
  836. ======================
  837.    Each element of a syntax table is an integer that translates into the
  838. full meaning of the entry: class, possible matching character, and
  839. flags.  However, it is not common for a programmer to work with the
  840. entries directly in this form since the Lisp-level syntax table
  841. functions usually work with syntax descriptors (*note Syntax
  842. Descriptors::.).
  843.    The low 8 bits of each element of a syntax table indicates the
  844. syntax class.
  845. Integer
  846.      Class
  847.      whitespace
  848.      punctuation
  849.      word
  850.      symbol
  851.      open parenthesis
  852.      close parenthesis
  853.      expression prefix
  854.      string quote
  855.      paired delimiter
  856.      escape
  857.      character quote
  858.      comment-start
  859.      comment-end
  860.    The next 8 bits are the matching opposite parenthesis (if the
  861. character has parenthesis syntax); otherwise, they are not meaningful.
  862. The next 6 bits are the flags.
  863. File: elisp,  Node: Abbrevs,  Next: Processes,  Prev: Syntax Tables,  Up: Top
  864. Abbrevs And Abbrev Expansion
  865. ****************************
  866.    An abbreviation or "abbrev" is a string of characters that may be
  867. expanded to a longer string.  The user can insert the abbrev string and
  868. find it replaced automatically with the expansion of the abbrev.  This
  869. saves typing.
  870.    The set of abbrevs currently in effect is recorded in an "abbrev
  871. table".  Each buffer has a local abbrev table, but normally all buffers
  872. in the same major mode share one abbrev table.  There is also a global
  873. abbrev table.  Normally both are used.
  874.    An abbrev table is represented as an obarray containing a symbol for
  875. each abbreviation.  The symbol's name is the abbreviation.  Its value is
  876. the expansion; its function definition is the hook; its property list
  877. cell contains the use count, the number of times the abbreviation has
  878. been expanded.  Because these symbols are not interned in the usual
  879. obarray, they will never appear as the result of reading a Lisp
  880. expression; in fact, they will never be used except by the code that
  881. handles abbrevs.  Therefore, it is safe to use them in an extremely
  882. nonstandard way.  *Note Creating Symbols::.
  883.    For the user-level commands for abbrevs, see *Note Abbrev Mode:
  884. (emacs)Abbrevs.
  885. * Menu:
  886. * Abbrev Mode::                 Setting up Emacs for abbreviation.
  887. * Tables: Abbrev Tables.        Creating and working with abbrev tables.
  888. * Defining Abbrevs::            Specifying abbreviations and their expansions.
  889. * Files: Abbrev Files.          Saving abbrevs in files.
  890. * Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
  891. * Standard Abbrev Tables::      Abbrev tables used by various major modes.
  892. File: elisp,  Node: Abbrev Mode,  Next: Abbrev Tables,  Prev: Abbrevs,  Up: Abbrevs
  893. Setting Up Abbrev Mode
  894. ======================
  895.    Abbrev mode is a minor mode controlled by the value of the variable
  896. `abbrev-mode'.
  897.  - Variable: abbrev-mode
  898.      A non-`nil' value of this variable turns on the automatic expansion
  899.      of abbrevs when their abbreviations are inserted into a buffer.
  900.      If the value is `nil', abbrevs may be defined, but they are not
  901.      expanded automatically.
  902.      This variable automatically becomes local when set in any fashion.
  903.  - Variable: default-abbrev-mode
  904.      This is the value `abbrev-mode' for buffers that do not override
  905.      it.  This is the same as `(default-value 'abbrev-mode)'.
  906.